---
title: First Prompty
authors:
  - bethanyjep
  - nitya
date: 2024-10-09
tags:
  - getting-started
  - documentation
  - quickstart
index: 4
---

_In the last section, we **Setup** our development environment by installing the Visual Studio Code extension. In this section, we'll create, configure, and run, our first Prompty asset._

## 1. Pre-requisites

To _run_ the Prompty, you will need a valid Large Language Model deployed endpoint you can configure. The Prompty specification currently supports three model providers:

1. **OpenAI** - requires the endpoint and key configuration properties
1. **Azure OpenAI** - requires the endpoint and uses keyless auth (with login)
1. **Serverless** - requires a GitHub Personal Access Token, uses [Marketplaces models](https://github.com/marketplace/models)

For our first Prompty, we'll focus on the Azure OpenAI option.
 - we assume you've deployed an _Azure OpenAI_ model 
 - we assume you've retrieved its Endpoint URL information
 - we assume you've installed the Prompty extension in VS Code

## 2. Create a Prompty asset

Open the Visual Studio Code editor, then click the `File Explorer` icon to view your project filesystem. Select a destination folder (e.g., could be the repository root) and _right-click_ to get a drop-down menu. Look for the `New Prompty` option and click it.

<details>
<summary> ☑ **You should see this `basic.prompty` file created** (click to expand) </summary>
```markdown
---
name: ExamplePrompt
description: A prompt that uses context to ground an incoming question
authors:
  - Seth Juarez
model:
  api: chat
  configuration:
    type: azure_openai
    azure_endpoint: ${env:AZURE_OPENAI_ENDPOINT}
    azure_deployment: <your-deployment>
    api_version: 2024-07-01-preview
  parameters:
    max_tokens: 3000
sample:
  firstName: Seth
  context: >
    The Alpine Explorer Tent boasts a detachable divider for privacy, 
    numerous mesh windows and adjustable vents for ventilation, and 
    a waterproof design. It even has a built-in gear loft for storing 
    your outdoor essentials. In short, it's a blend of privacy, comfort, 
    and convenience, making it your second home in the heart of nature!
  question: What can you tell me about your tents?
---

system:
You are an AI assistant who helps people find information. As the assistant, 
you answer questions briefly, succinctly, and in a personable manner using 
markdown and even add some personal flair with appropriate emojis.

# Customer
You are helping {{firstName}} to find answers to their questions.
Use their name to address them in your responses.

# Context
Use the following context to provide a more personalized response to {{firstName}}:
{{context}}

user:
{{question}}

```
</details>

## 3. Update the default Prompty

You can now update the file contents as shown below. Here, we have made three changes:

- We changed the frontmatter (metadata) to customize _name, description, authors_
- We updated the model (configuration) to reflect the _endpoint, deployment_
- We updated the content (template) to tailor response behavior _with examples_

Note that we updated the model to get its endpoint information from a `AZURE_OPENAI_ENDPOINT` environment variable. Make sure you set this in the terminal, or in a `.env` file at the root of the repo.

<details>
<summary> ☑ **This is our updated `shakespeare.prompty` asset** (click to expand) </summary>
```markdown
---
name: Shakespearean Writing Prompty
description: A prompt that answers questions in Shakespearean style using GPT-4
authors:
  - Bethany Jepchumba
model:
  api: chat
  configuration:
    type: azure_openai
    azure_endpoint: ${env:AZURE_OPENAI_ENDPOINT}
    azure_deployment: gpt-4
  parameters:
    max_tokens: 3000
sample:
  question: Please write a short text inviting friends to a Game Night.
---

system:
You are a Shakespearean writing assistant who speaks in a Shakespearean style. You help people come up with creative ideas and content like stories, poems, and songs that use Shakespearean style of writing style, including words like "thou" and "hath”.
Here are some example of Shakespeare's style:
- Romeo, Romeo! Wherefore art thou Romeo?
- Love looks not with the eyes, but with the mind; and therefore is winged Cupid painted blind.
- Shall I compare thee to a summer's day? Thou art more lovely and more temperate.

example:
user: Please write a short text turning down an invitation to dinner.
assistant: Dearest,
  Regretfully, I must decline thy invitation.
  Prior engagements call me hence. Apologies.

user:
{{question}}
```
</details>

## 4. Run the Prompty
You can now run the Prompty by clicking the `Play` button (top right) in the editor pane of your `.prompty` file.

1. You will see a pop-up asking you to authenticate with Azure. **Sign in**
2. You will see the VS Code terminal switch to the `Outputs` tab. **View output**
The first step ensures that we use Azure managed identity to authenticate with the specified Azure OpenAI endpoint - and don't need to use explicitly defined keys. You only need to authenticate once. You can then iterate rapidly on prompty content ("prompt engineering") and run it for instant responses. We recommend clearing the output terminal after each run, for clarity.
<details>
<summary> ☑️ **This is a sample response from one prompty run**. (click to expand) </summary>

```bash
Friends most dear,

I do entreat thee to join me for an evening of mirth and games anon. 
Let us gather our wits and spirits for a night of sport and jest.

Thy presence would bring great joy.

Yours in fellowship,
[Your Name]
```
</details>


## 5. How Prompty assets work

The `.prompty` file is an example of a Prompty _asset_ that respects the schema defined in the Prompty specification. The asset class is language-agnostic (not tied to any language or framework), using a _markdown format with YAML_ to specify metadata ("frontmatter") and content ("template") for a _single prompt-based interaction_ with a Large Language Model. By doing this, it **unifies the prompt content and its execution context in a single asset package**, making it easy for developers to rapidly iterate on prompts for prototyping.

The _frontmatter_ (metadata) is structured as YAML, and specifies the prompt inputs, outputs, and model configuration parameters - with optional sample data for testing. The _content_ (template) forms the body of the asset and is a _Jnja_ template that allows for dynamic data binding of variables from Prompty asset inputs. The ability to specify sample data for testing (as an inline object or an external filename) allows us to use Prompty to iteratively **define the shape of the data required in complex flows** at the granularity of single LLM calls. 

The asset is then _activated_ by a Prompty runtime as follows:
1. The file asset is **loaded**, converting it into an executable function.
1. The asset is now **rendered**, using function parameters to fill in the template data.
1. The asset is then **executed**, invoking the configured model with the rendered template.
The returned result can then be displayed to the caller (single node) or can be passed as the input to a different Prompty asset (chained flow) to support more complex orchestration.

## 6. How Models Are Configured

Prompty assets must be configured with a _model_ that is the target for the prompt request. However, this configuration can happen at different levels, with a hierarchy that decides which value takes final precedence during execution.

1. The Visual Studio Code environment defines a _default_ configuration that you can view by clicking on the `Prompty default` tab in the bottom toolbar. If a Prompty asset does not specify an explicit model configuration, the invocation will use the default model.
1. When we convert a Prompty asset to code, you may see a `prompty.json` file with a default configuration. This is equivalent to the Visual Studio Code default, but applied to the case when we execute the Prompty from code (vs. VS Code editor).
1. The Prompty file can itself define model configuration in the _frontmatter_ as seen in our example Prompty (see snippet below). When specified, this value will override other defaults.
In our example asset (snippet below), the Prompty file **explicitly defines** model configuration properties, giving it precedence. Note also that property values can be specified as constants (`gpt-4`) or reference environment variables (`${env:AZURE_OPENAI_ENDPOINT}`). The latter is the recommended approach, ensuring that secrets don't get checked into version control with asset file updates.

```yaml
model:
  api: chat
  configuration:
    type: azure_openai
    azure_endpoint: ${env:AZURE_OPENAI_ENDPOINT}
    azure_deployment: gpt-4
  parameters:
    max_tokens: 3000
```

**Tip 1: Configure Model in VS Code**. If you use the same model configuration repeatedly, or across multiple Prompty assets, consider setting it up as a _named_ model in Visual Studio Code.To configure your model, navigate to and edit your ``settings.json`` file. You can edit this by navigating to ``settings > Extensions > Prompty > Edit in settings.json``. Update an existing named model (e.g., `default`) or create a new one. _You can update this at user level (across your assets) or workspace level (across team assets)._ 

**Tip 2: Use Azure Managed Identity**. If you are using Azure OpenAI or Azure-managed models, opt for _keyless authentication_ by logging into Azure Active Directory (from Prompty extension, once per session) and using that credential to authenticate with your Azure OpenAI model deployments. _To trigger this authflow, leave the `api_key` property value empty in your model configuration_.

**Tip 3: Use Environment Variables**. As shown above, property values can be defined using environment variables in the format ``${env:ENVAR_NAME}``. By default, the Visual Studio Code extension will look for a `.env` file in the root folder of the repository containing Prompty assets - create and update that file (and ensure it is .gitignore-d by default). _If you use GitHub Codespaces, you can also store environment variables as Codespaces secrets that get automatically injected into the runtime at launch_.

## 7. How To Observe Output

By default, executing the Prompty will open the _Output_ tab on the Visual Studio Code terminal and show a _brief response_ with the model output. But what if you want more detail? Prompty provides two features that can help.

1. **Terminal Options** - Look for the `Prompty Output (verbose)` option in a drop-down menu in the Visual Studio Code terminal (at top left of terminal). Selecting this option gives you verbose output which includes the _request_ details and _response_ details, including useful information like token usage for execution.
1. **Code Options** - When assets are converted to code, you can take advantage of _Prompty Tracer_ features to log execution traces to the console, or to a JSON file, that can then be visualized for richer analysis of the flow steps and performance.

## 8. How To Generate Code

In this section, we focused on Prompty asset creation and execution from the Visual Studio Code editor (no coding involved). Here, the Visual Studio Code extension acts as the default runtime, loading the asset, rendering the template, and executing the model invocation transparently. But this approach will not work when we need to **orchestrate** complex flows with multiple assets, or when we need to **automate** execution in CI/CD pipelines.

This is where the _Prompty Runtime_ comes in. The runtime converts the Prompty asset into code that uses a preferred language or framework. We can think of "runtimes" in two categories:

- **Core Runtimes** - generate basic code in the target language. Examples: Python, C#
- **Framework-Enabled** - generate code for a specific framework. Examples: LangChain, Semantic Kernel

*In the next section, we'll explore how to go from Prompty To Code, using the core Python runtime*.


---
[Want to Contribute To the Project?](/contributing/) - _Updated Guidance Coming Soon_.
